Error handling

---

Keepz API errors follow a standardized format. Each error is returned with an HTTP status code (in the response header) and a JSON body:

{
  "message": "You do not have permission to save card!",
  "statusCode": 6031,
  "exceptionGroup": 3
}

Fields:

Parameter	Type	Description
message	string	Human-readable error description.
statusCode	number	Unique error code assigned by Keepz.
exceptionGroup	number	Numeric identifier of the exception group.

Exception Groups

Errors are grouped into categories to simplify handling. The value of exceptionGroup in the response corresponds to one of the following:

Group	Value	Typical HTTP Status Codes	Description
VALIDATION	1	400 Bad Request	Input/data validation failures
BUSINESS_LOGIC	2	409 Conflict, 410 Gone, 429 Too Many Requests, 451 Unavailable For Legal Reasons	Violations of domain rules or state
AUTH	3	403 Forbidden	Permission/authorization issues
EXTERNAL_REST	4	502 Bad Gateway, 500 Internal Server Error,	Errors calling external/third-party systems
RESOURCE_NOT_FOUND	5	404 Not Found	Missing or inactive resources
GENERAL	6	`500 Internal Server	Unexpected system/runtime issues
INTERNAL_REST	7	500 Internal Server Error	Errors calling internal services

Status codes by Group

Resurces not found

Code	Message
6002	Active check order not found
6004,6008	Active Integrator not found
6005	Integrator order not found
6030	Tip receiver not found
6044	Active third party not found
6045	Third party order not found
6046	Order not found
6075	Integrator card not found
6093	DEFAULT direct link provider not found
6100	Subscription plan not found
6112	Subscription plan history not found

Business logic

Code	Message
6003	Integrator order expired
6006	Order not found or already finalised and can't be canceled
6015	Order is not valid anymore
6016	Order is already paid
6017	Order is expired
6023	Order with this integratorOrderId already exists
6024	Receiver type must be 'BRANCH'
6034	Provided more than one direct link provider

Validation

Code	Message

Code	Message
6007	Refund amount out of range
6026	Amount out of limit range
6027	Given initiate currency is not allowed
6028	Given distribution currency is not allowed
6029	Given acquiring currency is not allowed
6035	validUntil must be a future date
6041	Invalid date range
6049	Invalid integrator order create param
6053	Not valid method argument
6058	Amount scale is more than 2 after floating point
6059	Split amount sum is not equal to main amount
6060	In split details main receiver not found
6061	In split details main receiver is included more than once
6064	Split details not provided
6062	Split details less than 2 size
6066	Split amount sum is greater than main amount
6068	Amount must be greater than zero
6070	Personal number is required
6076	Integrator order properties cannot be null
6077	Invalid order property value
6078	Missing order property value
6079	Invalid order property field
6081	Amount is different from service provider debt
6082	XML signature validation failed
6085	Invalid integrator type
6086	RS order is in payment process already
6087	RS order is already paid
6088	RS order not valid for payment anymore
6091	Direct link provider is required
6094	Partial refund not allowed without details
6095	Order refund param validation failed
6096	Invalid refund details
6097	Duplicated receiver
6098	Invalid split receiver type
6099	Invalid split receiver identifier format
6101	Given payment provider not allowed for subscription
6109	Invalid third party order create param
6110	Invalid third party order finalise param
6113	Amount must be zero
6021	Number format is not valid

General

Code	Message
6009	Failed to encrypt data
6010	Failed to decrypt data
6011	Failed to parse data
6013	Failed to decrypt data using AES
6014	Failed to encrypt data using AES
6054	Unhandled general exception

Auth

Code	Message
6022	No permission to create orders
6025	No permission to create multi currency orders
6031	No permission to save card
6032	No permission to define order expire date
6033	No permission to receive direct link
6036	No permission to use dynamic redirect
6037	No permission to use additional fields
6038	No permission to use refund
6090	No permission to pay with saved card!
6111	No permission for subscription
6056	No permission to use dynamic callback
6057	No permission to use split functionality

Error Handling Best Practices

To ensure smooth troubleshooting and faster resolution, integrators should:

• Log the full error response (message, statusCode, exceptionGroup, and the HTTP status).

• Identify the exception group to understand the error category (e.g., AUTH means a permission issue).

• Retry carefully:

  • Do not retry validation/auth errors — fix the request instead.

  • Business logic and external REST errors may sometimes succeed after retry.

• Escalate when needed: If you encounter an unknown statusCode or unclear error, forward the logged details to Keepz Support.